home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 23 / Amiga Format AFCD23 (Feb 1998, Issue 107).iso / -seriously_amiga- / shareware / programming / other / fdi / fdi.doc < prev    next >
Text File  |  1997-12-01  |  7KB  |  196 lines
  1.             FDI v2.2
  2.             © Karl J. Ots
  3.             29 October 1997
  4.         
  5.         EMail:    kjots@gem.menzies.latrobe.edu.au
  6.         WWW:    http://gem.menzies.latrobe.edu.au/~kjots
  7. Note:
  8.     This is not an upgrade, just a repackaging.  I am quite happy
  9.     with the way FDI work, but I have changed both my email/WWW
  10.     address and got a new compiler, so I've deciced to re-release
  11.     FDI to reflect these changes.
  12.  
  13. Discalimer:
  14.     This program was written primarily for my own use, but it was 
  15.     so useful I have decided to release in as FreeWare.  I retain 
  16.     the rights on the source code, however. You may view it for your
  17.     education, or even alter it if it needs to run differenty on your
  18.     system, as long as you don't distribute the altered code.  Send
  19.     me reports of whatever the problem is, and I'll try to fix it.
  20.     
  21.     All components of this archive must accompany the executable in
  22.     any distribution.  No charge may be made, other than to cover 
  23.     costs of disks and/or postage.  
  24.     
  25.     The author can in no way be held responsibe for any problems 
  26.     arising from the use of this program, or any files generated
  27.     by it.  All I can say is that is works on my system.  It should
  28.     work on yours.
  29.  
  30. Description:
  31.     Why another FD to Assembly include file converter? There has to be
  32.     hundreds of them out there!  Well, if that's the case, why can't 
  33.     find one to do what I want it to?
  34.     
  35.     My desires for an Include file has it in a neat, readable form, 
  36.     several variations of CALL Macros, and with hexidecimal offsets.
  37.     Many programs offer one or two of them (neat output but decimal
  38.     offsets, hexidedimal output but no CALL macros, etc), but not all,
  39.     and none of them do the RCALL or SCALL macros.  So, I wrote one 
  40.     that does.
  41.     
  42.     FDI offers:
  43.         * Three CALL macros:
  44.            - Standard,
  45.            - PC-Reletive base movement,
  46.            - Simple - no base movement.
  47.         * Hexidecimal or Decimal offsets.
  48.         * Neat, tab-alligned output (with variable tabs).
  49.         * Non-include flile output represion for easy scripting.
  50.         * Private entries can be processed or ommited.
  51.     
  52.     All options are controlled, and it is up to YOU which one you
  53.     want to use.
  54.     
  55. Use:
  56.     FDI can be run from the Shell only, and uses ReadArgs, so
  57.     it can only be run on OS2 (v36) or above. The template looks
  58.     like this:
  59.     
  60.     FROM/A,TO,MAXTABS/N,CALL/S,RCALL/S,SCALL/S,DEC/S,NOBAN/S,QUIET/S:
  61.  
  62.     At first look, there seem to be a lot of command line arguments,
  63.     but the program will work without most of them.  In fact, the 
  64.     only one you have to specify is the FROM field.
  65.     
  66.     A brief description:
  67.     
  68.     FROM    FD file name.
  69.     TO    Include file name.
  70.     CALL    Make CALL Macro.
  71.     RCALL    Make RCALL Macro.
  72.     SCALL    Make SCALL Macro.
  73.     DEC    Make decimal offsets.
  74.     PRIV    Process private entries.
  75.     NOBAN    Repress output of program banner.
  76.     QUIET    Repress all non-include output.
  77.     
  78.     The decription below covers all arguments in depth, and the 
  79.     examples are taken from the exec_lib.fd file (unless indicated).
  80.     
  81.     Files
  82.     -----
  83.     
  84.     FROM    The name and path of the FD file you want to convert.  
  85.         Only one file may be specified (see "Scripting" below).
  86.         The name of the file will be included at the top of the
  87.         Include file (eg "...converted form FD:exec_lib.fd...").
  88.         Must be specified.
  89.     
  90.     TO    The name and path of the Include file output.  If not 
  91.         included, the output will be sent to the STDOUT (ie the
  92.         Shell).
  93.     
  94.     Macros
  95.     ------
  96.     
  97.     CALL    This switch will cause a CALL Macro to be generated.
  98.         The macro will look like this:
  99.         
  100.         CALLSYS    macro
  101.             move.l    _SysBase,a6
  102.             jsr    \1(a6)
  103.             emdm
  104.         
  105.     RCALL    This switch will make a simlar CALL Macro, except that
  106.         the base will move moved PC-reletive, thus:
  107.         
  108.         RCALLSYS    macro
  109.             move.l    _SysBase(pc),a6
  110.             jsr    \1(a6)
  111.             endm
  112.         
  113.         Note that the above will make no sense if _SysBase is 
  114.         set "EQU 4", (rather than "dc.l $C00AA8" for 2.04, which
  115.         you should never use).  This won't matter if you don't use
  116.         the macro.  It is made because I didn't want to make 
  117.         library-specific macros.  
  118.     
  119.     SCALL    This is also like the the above macro, except SCALL (for
  120.         Simple Call) will ommit the base movement alogether:
  121.         
  122.         SCALLSYS    macro
  123.             jsr    _\1(a6)
  124.             endm
  125.     
  126.         Now,  this macro will be identical for all libraries 
  127.         (except for the name).  It was made because 
  128.         (1) It is good programming to indicate where the function
  129.             is comming from;
  130.         (2) Any of the other macros can be called with only 
  131.             changing one letter, which is move convenient.
  132.     
  133.     Macros require the ##base field of the FD file to be set (even
  134.     SCALL).  The only V40 FD file that fails in this is "cia_lib.fd"
  135.     An error message will be output if this happens, and will not 
  136.     affect the rest of the conversion.
  137.     
  138.     Processing
  139.     ----------
  140.     
  141.     MAXTABS    The mamximum numer of tabs to include on each line, to 
  142.         make the EQU's all line up and be easier to read.  The 
  143.         default is 4, which will ensure all lines converted from
  144.         the V40 FD files are neat.  Other files with long 
  145.         function names may need larger values.
  146.     
  147.     DEC    I use hexidecmal offsets in my include files:
  148.         
  149.         _LVOSupervisor            EQU    -$001E
  150.         
  151.         Many people like decimal offsets:
  152.         
  153.         _LVOSupervisor            EQU    -30
  154.         
  155.         Is use hex because that is how it is represented by most
  156.         debuggers, monitors and disassemblers (eg MonAm).  It makes
  157.         it easier to locate the functions name.  This switch will
  158.         force the program to generate decimal offsets.
  159.     
  160.     PRIV    There are many private entries in FD files, and they 
  161.         shouldn't be used by most people (The don't even describe
  162.         the arguments in the V40 FD's).  But in some cases, such
  163.         as system programming, or if you are writting the library
  164.         yourself, you might need access to the private entries.
  165.         The PRIV switch will process the private entries, otherwise
  166.         they will be skipped.
  167.     
  168.     STDERR Output
  169.     -------------
  170.     
  171.     NOBAN    The banner is output every time the program is executed,
  172.         telling everone who wrote it (me!) and what it is.  This 
  173.         can be a hassle if you're using a script to convert many
  174.         files at once.  This will cause the banner not to be
  175.         written, but will not affect the other coversion 
  176.         information.
  177.     
  178.     QUIET    This will repress all non-include file output (causing
  179.         them to be written to NIL:).  Good if you want to execute
  180.         the program from the WB, using the "Execute" menu item.
  181.         with QUIET, and TO specified, an output window will not
  182.         be opened.
  183.  
  184. Sripting:
  185.     Although only one file may be converted at once, you can use 
  186.     "List" to create a script that will convert many files on once.
  187.     Simply type:
  188.     
  189.     List FD:#?.fd TO name LFORMAT "FDI FROM %s%s TO %m.i <option> "
  190.     
  191.     At the command line to get a script called "name", which can be 
  192.     executed.  The options are the ones you want to affect all the 
  193.     files.  Note the %m: this will strip the ".fd" off the file (and 
  194.     we put on ".i").  For more info, see the AmigaDOS information on
  195.     List, as well as the FDI.scr file included in this archive.
  196.